Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/python/pythnlbn.lha/python-lib.info-4

GNU Info File | 1993-07-29 | 48.7 KB | 1,328 lines

This is Info file python-lib.info, produced by Makeinfo-1.43 from the
input file @out.texi.

This file describes the built-in types, exceptions and functions and
the standard modules that come with the Python system.  It assumes
basic knowledge about the Python language.  For an informal
introduction to the language, see the Python Tutorial.  The Python
Reference Manual gives a more formal definition of the language.
(These manuals are not yet available in INFO or Texinfo format.)

Copyright (C) 1991, 1992, 1993 by Stichting Mathematisch Centrum,
Amsterdam, The Netherlands.

All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the names of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


File: python-lib.info,  Node: SGI MACHINES ONLY,  Next: SUN SPARC MACHINES ONLY,  Prev: STDWIN ONLY,  Up: Top

SGI MACHINES ONLY
*****************

* Menu:

* al::                          Built-in Module `al'
* AL (uppercase)::              Standard Module `AL'
* audio::                       Built-in Module `audio'
* gl::                          Built-in Module `gl'
* fm::                          Built-in Module `fm'
* Standard Modules GL and DEVICE::  Standard Modules `GL' and `DEVICE'
* fl::                          Built-in Module `fl'
* FL (uppercase)::              Standard Module `FL'
* flp::                         Standard Module `flp'
* panel::                       Standard Module `panel'
* panelparser::                 Standard Module `panelparser'
* pnl::                         Built-in Module `pnl'
* jpeg::                        Built-in Module `jpeg'
* imgfile::                     Built-in module `imgfile'
* imageop::                     Built-in module `imageop'


File: python-lib.info,  Node: al,  Next: AL (uppercase),  Up: SGI MACHINES ONLY

Built-in Module `al'
====================

This module provides access to the audio facilities of the Indigo and
4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
(and also available as an option in IRIX 3.3).  You'll need to read
those man pages to understand what these functions do!  Some of the
functions are not available in releases below 4.0.5.  Again, see the
manual to check whether a specific function is available on your
platform.

Symbolic constants from the C header file `<audio.h>' are defined in
the standard module `AL', see below.

*Warning:* the current version of the audio library may dump core when
bad argument values are passed rather than returning an error status.
Unfortunately, since the precise circumstances under which this may
happen are undocumented and hard to check, the Python interface can
provide no protection against this kind of problems.  (One example is
specifying an excessive queue size -- there is no documented upper
limit.)

Module `al' defines the following functions:

 -- function of module al: openport (NAME, DIRECTION, CONFIG)
     Equivalent to the C function ALopenport().  The name and direction
     arguments are strings.  The optional config argument is an opaque
     configuration object as returned by `al.newconfig()'.  The return
     value is an opaque port object; methods of port objects are
     described below.

 -- function of module al: newconfig ()
     Equivalent to the C function ALnewconfig().  The return value is
     a new opaque configuration object; methods of configuration
     objects are described below.

 -- function of module al: queryparams (DEVICE)
     Equivalent to the C function ALqueryparams().  The device
     argument is an integer.  The return value is a list of integers
     containing the data returned by ALqueryparams().

 -- function of module al: getparams (DEVICE, LIST)
     Equivalent to the C function ALgetparams().  The device argument
     is an integer.  The list argument is a list such as returned by
     `queryparams'; it is modified in place (!).

 -- function of module al: setparams (DEVICE, LIST)
     Equivalent to the C function ALsetparams().  The device argument
     is an integer.The list argument is a list such as returned by
     `al.queryparams'.

Configuration objects (returned by `al.newconfig()' have the following
methods:

 -- Method on audio configuration object: getqueuesize ()
     Return the queue size; equivalent to the C function
     ALgetqueuesize().

 -- Method on audio configuration object: setqueuesize (SIZE)
     Set the queue size; equivalent to the C function ALsetqueuesize().

 -- Method on audio configuration object: getwidth ()
     Get the sample width; equivalent to the C function ALgetwidth().

 -- Method on audio configuration object: getwidth (WIDTH)
     Set the sample width; equivalent to the C function ALsetwidth().

 -- Method on audio configuration object: getchannels ()
     Get the channel count; equivalent to the C function
     ALgetchannels().

 -- Method on audio configuration object: setchannels (NCHANNELS)
     Set the channel count; equivalent to the C function
     ALsetchannels().

 -- Method on audio configuration object: getsampfmt ()
     Get the sample format; equivalent to the C function
     ALgetsampfmt().

 -- Method on audio configuration object: setsampfmt (SAMPFMT)
     Set the sample format; equivalent to the C function
     ALsetsampfmt().

 -- Method on audio configuration object: getfloatmax ()
     Get the maximum value for floating sample formats; equivalent to
     the C function ALgetfloatmax().

 -- Method on audio configuration object: setfloatmax (FLOATMAX)
     Set the maximum value for floating sample formats; equivalent to
     the C function ALsetfloatmax().

Port objects (returned by `al.openport()' have the following methods:

 -- Method on audio port object: closeport ()
     Close the port; equivalent to the C function ALcloseport().

 -- Method on audio port object: getfd ()
     Return the file descriptor as an int; equivalent to the C function
     ALgetfd().

 -- Method on audio port object: getfilled ()
     Return the number of filled samples; equivalent to the C function
     ALgetfilled().

 -- Method on audio port object: getfillable ()
     Return the number of fillable samples; equivalent to the C
     function ALgetfillable().

 -- Method on audio port object: readsamps (NSAMPLES)
     Read a number of samples from the queue, blocking if necessary;
     equivalent to the C function ALreadsamples.  The data is returned
     as a string containing the raw data (e.g. 2 bytes per sample in
     big-endian byte order (high byte, low byte) if you have set the
     sample width to 2 bytes.

 -- Method on audio port object: writesamps (SAMPLES)
     Write samples into the queue, blocking if necessary; equivalent
     to the C function ALwritesamples.  The samples are encoded as
     described for the `readsamps' return value.

 -- Method on audio port object: getfillpoint ()
     Return the `fill point'; equivalent to the C function
     ALgetfillpoint().

 -- Method on audio port object: setfillpoint (FILLPOINT)
     Set the `fill point'; equivalent to the C function
     ALsetfillpoint().

 -- Method on audio port object: getconfig ()
     Return a configuration object containing the current
     configuration of the port; equivalent to the C function
     ALgetconfig().

 -- Method on audio port object: setconfig (CONFIG)
     Set the configuration from the argument, a configuration object;
     equivalent to the C function ALsetconfig().

 -- Method on audio port object: getstatus (LIST)
     Get status information on last error equivalent to C function
     ALgetstatus().


File: python-lib.info,  Node: AL (uppercase),  Next: audio,  Prev: al,  Up: SGI MACHINES ONLY

Standard Module `AL'
====================

This module defines symbolic constants needed to use the built-in
module `al' (see above); they are equivalent to those defined in the C
header file `<audio.h>' except that the name prefix `AL_' is omitted.
Read the module source for a complete list of the defined names.
Suggested use:

     import al
     from AL import *


File: python-lib.info,  Node: audio,  Next: gl,  Prev: AL (uppercase),  Up: SGI MACHINES ONLY

Built-in Module `audio'
=======================

*Note:* This module is obsolete, since the hardware to which it
interfaces is obsolete.  For audio on the Indigo or 4D/35, see
built-in module `al' above.

This module provides rudimentary access to the audio I/O device
`/dev/audio' on the Silicon Graphics Personal IRIS 4D/25; see
audio(7). It supports the following operations:

 -- function of module audio: setoutgain (N)
     Sets the output gain.  `0 <= N < 256'.

 -- function of module audio: getoutgain ()
     Returns the output gain.

 -- function of module audio: setrate (N)
     Sets the sampling rate: `1' = 32K/sec, `2' = 16K/sec, `3' =
     8K/sec.

 -- function of module audio: setduration (N)
     Sets the `sound duration' in units of 1/100 seconds.

 -- function of module audio: read (N)
     Reads a chunk of N sampled bytes from the audio input (line in or
     microphone).  The chunk is returned as a string of length n.
     Each byte encodes one sample as a signed 8-bit quantity using
     linear encoding.  This string can be converted to numbers using
     `chr2num()' described below.

 -- function of module audio: write (BUF)
     Writes a chunk of samples to the audio output (speaker).

These operations support asynchronous audio I/O:

 -- function of module audio: start_recording (N)
     Starts a second thread (a process with shared memory) that begins
     reading N bytes from the audio device.  The main thread
     immediately continues.

 -- function of module audio: wait_recording ()
     Waits for the second thread to finish and returns the data read.

 -- function of module audio: stop_recording ()
     Makes the second thread stop reading as soon as possible.
     Returns the data read so far.

 -- function of module audio: poll_recording ()
     Returns true if the second thread has finished reading (so
     `wait_recording()' would return the data without delay).

 -- function of module audio: start_playing ()

 -- function of module audio: wait_playing ()

 -- function of module audio: stop_playing ()

 -- function of module audio: poll_playing ()
     Similar but for output.  `stop_playing()' returns a lower bound
     for the number of bytes actually played (not very accurate).


The following operations do not affect the audio device but are
implemented in C for efficiency:

 -- function of module audio: amplify (BUF, F1, F2)
     Amplifies a chunk of samples by a variable factor changing from
     `F1/256' to `F2/256.' Negative factors are allowed.  Resulting
     values that are to large to fit in a byte are clipped.

 -- function of module audio: reverse (BUF)
     Returns a chunk of samples backwards.

 -- function of module audio: add (BUF1, BUF2)
     Bytewise adds two chunks of samples.  Bytes that exceed the range
     are clipped.  If one buffer is shorter, it is assumed to be
     padded with zeros.

 -- function of module audio: chr2num (BUF)
     Converts a string of sampled bytes as returned by `read()' into a
     list containing the numeric values of the samples.

 -- function of module audio: num2chr (LIST)
     Converts a list as returned by `chr2num()' back to a buffer
     acceptable by `write()'.



File: python-lib.info,  Node: gl,  Next: fm,  Prev: audio,  Up: SGI MACHINES ONLY

Built-in Module `gl'
====================

This module provides access to the Silicon Graphics *Graphics Library*.
It is available only on Silicon Graphics machines.

*Warning:* Some illegal calls to the GL library cause the Python
interpreter to dump core.  In particular, the use of most GL calls is
unsafe before the first window is opened.

The module is too large to document here in its entirety, but the
following should help you to get started.  The parameter conventions
for the C functions are translated to Python as follows:

   * All (short, long, unsigned) int values are represented by Python
     integers.

   * All float and double values are represented by Python floating
     point numbers.  In most cases, Python integers are also allowed.

   * All arrays are represented by one-dimensional Python lists.  In
     most cases, tuples are also allowed.

   * All string and character arguments are represented by Python
     strings, for instance, `winopen('Hi There!')' and `rotate(900,
     'z')'.

   * All (short, long, unsigned) integer arguments or return values
     that are only used to specify the length of an array argument are
     omitted.  For example, the C call

          lmdef(deftype, index, np, props)
     is translated to Python as

          lmdef(deftype, index, props)

   * Output arguments are omitted from the argument list; they are
     transmitted as function return values instead.  If more than one
     value must be returned, the return value is a tuple.  If the C
     function has both a regular return value (that is not omitted
     because of the previous rule) and an output argument, the return
     value comes first in the tuple.  Examples: the C call

          getmcolor(i, &red, &green, &blue)
     is translated to Python as

          red, green, blue = getmcolor(i)

The following functions are non-standard or have special argument
conventions:

 -- function of module gl: varray (ARGUMENT)
     Equivalent to but faster than a number of `v3d()' calls.  The
     ARGUMENT is a list (or tuple) of points.  Each point must be a
     tuple of coordinates `(X, Y, Z)' or `(X, Y)'.  The points may be
     2- or 3-dimensional but must all have the same dimension.  Float
     and int values may be mixed however.  The points are always
     converted to 3D double precision points by assuming `Z = 0.0' if
     necessary (as indicated in the man page), and for each point
     `v3d()' is called.

 -- function of module gl: nvarray ()
     Equivalent to but faster than a number of `n3f' and `v3f' calls.
     The argument is an array (list or tuple) of pairs of normals and
     points.  Each pair is a tuple of a point and a normal for that
     point.  Each point or normal must be a tuple of coordinates `(X,
     Y, Z)'.  Three coordinates must be given.  Float and int values
     may be mixed.  For each pair, `n3f()' is called for the normal,
     and then `v3f()' is called for the point.

 -- function of module gl: vnarray ()
     Similar to `nvarray()' but the pairs have the point first and the
     normal second.

 -- function of module gl: nurbssurface (S_K, T_K, CTL, S_ORD, T_ORD,
          TYPE)
     Defines a nurbs surface.  The dimensions of `CTL[][]' are
     computed as follows: `[len(S_K) - S_ORD]', `[len(T_K) - T_ORD]'.

 -- function of module gl: nurbscurve (KNOTS, CTLPOINTS, ORDER, TYPE)
     Defines a nurbs curve.  The length of ctlpoints is `len(KNOTS) -
     ORDER'.

 -- function of module gl: pwlcurve (POINTS, TYPE)
     Defines a piecewise-linear curve.  POINTS is a list of points.
     TYPE must be `N_ST'.

 -- function of module gl: pick (N)

 -- function of module gl: select (N)
     The only argument to these functions specifies the desired size
     of the pick or select buffer.

 -- function of module gl: endpick ()

 -- function of module gl: endselect ()
     These functions have no arguments.  They return a list of
     integers representing the used part of the pick/select buffer.
     No method is provided to detect buffer overrun.

Here is a tiny but complete example GL program in Python:

     import gl, GL, time

     def main():
         gl.foreground()
         gl.prefposition(500, 900, 500, 900)
         w = gl.winopen('CrissCross')
         gl.ortho2(0.0, 400.0, 0.0, 400.0)
         gl.color(GL.WHITE)
         gl.clear()
         gl.color(GL.RED)
         gl.bgnline()
         gl.v2f(0.0, 0.0)
         gl.v2f(400.0, 400.0)
         gl.endline()
         gl.bgnline()
         gl.v2f(400.0, 0.0)
         gl.v2f(0.0, 400.0)
         gl.endline()
         time.sleep(5)

     main()


File: python-lib.info,  Node: fm,  Next: Standard Modules GL and DEVICE,  Prev: gl,  Up: SGI MACHINES ONLY

Built-in Module `fm'
====================

This module provides access to the IRIS *Font Manager* library.  It is
available only on Silicon Graphics machines.  See also: 4Sight User's
Guide, Section 1, Chapter 5: Using the IRIS Font Manager.

This is not yet a full interface to the IRIS Font Manager.  Among the
unsupported features are: matrix operations; cache operations;
character operations (use string operations instead); some details of
font info; individual glyph metrics; and printer matching.

It supports the following operations:

 -- function of module fm: init ()
     Initialization function.  Calls `fminit()'.  It is normally not
     necessary to call this function, since it is called automatically
     the first time the `fm' module is imported.

 -- function of module fm: findfont (FONTNAME)
     Return a font handle object.  Calls `fmfindfont(FONTNAME)'.

 -- function of module fm: enumerate ()
     Returns a list of available font names.  This is an interface to
     `fmenumerate()'.

 -- function of module fm: prstr (STRING)
     Render a string using the current font (see the `setfont()' font
     handle method below).  Calls `fmprstr(STRING)'.

 -- function of module fm: setpath (STRING)
     Sets the font search path.  Calls `fmsetpath(string)'.  (XXX Does
     not work!?!)

 -- function of module fm: fontpath ()
     Returns the current font search path.

Font handle objects support the following operations:

 -- Method on font handle: scalefont (FACTOR)
     Returns a handle for a scaled version of this font.  Calls
     `fmscalefont(FH, FACTOR)'.

 -- Method on font handle: setfont ()
     Makes this font the current font.  Note: the effect is undone
     silently when the font handle object is deleted.  Calls
     `fmsetfont(FH)'.

 -- Method on font handle: getfontname ()
     Returns this font's name.  Calls `fmgetfontname(FH)'.

 -- Method on font handle: getcomment ()
     Returns the comment string associated with this font.  Raises an
     exception if there is none.  Calls `fmgetcomment(FH)'.

 -- Method on font handle: getfontinfo ()
     Returns a tuple giving some pertinent data about this font.  This
     is an interface to `fmgetfontinfo()'.  The returned tuple
     contains the following numbers: `(PRINTERMATCHED, FIXED_WIDTH,
     XORIG, YORIG, XSIZE, YSIZE, HEIGHT, NGLYPHS)'.

 -- Method on font handle: getstrwidth (STRING)
     Returns the width, in pixels, of the string when drawn in this
     font.  Calls `fmgetstrwidth(FH, STRING)'.


File: python-lib.info,  Node: Standard Modules GL and DEVICE,  Next: fl,  Prev: fm,  Up: SGI MACHINES ONLY

Standard Modules `GL' and `DEVICE'
==================================

These modules define the constants used by the Silicon Graphics
*Graphics Library* that C programmers find in the header files
`<gl/gl.h>' and `<gl/device.h>'.  Read the module source files for
details.


File: python-lib.info,  Node: fl,  Next: FL (uppercase),  Prev: Standard Modules GL and DEVICE,  Up: SGI MACHINES ONLY

Built-in Module `fl'
====================

This module provides an interface to the FORMS Library by Mark
Overmars, version 2.0b.  For more info about FORMS, write to
[e-mail].

Most functions are literal translations of their C equivalents,
dropping the initial `fl_' from their name.  Constants used by the
library are defined in module `FL' described below.

The creation of objects is a little different in Python than in C:
instead of the `current form' maintained by the library to which new
FORMS objects are added, all functions that add a FORMS object to a
button are methods of the Python object representing the form.
Consequently, there are no Python equivalents for the C functions
`fl_addto_form' and `fl_end_form', and the equivalent of `fl_bgn_form'
is called `fl.make_form'.

Watch out for the somewhat confusing terminology: FORMS uses the word
"object" for the buttons, sliders etc. that you can place in a form.
In Python, `object' means any value.  The Python interface to FORMS
introduces two new Python object types: form objects (representing an
entire form) and FORMS objects (representing one button, slider etc.).
Hopefully this isn't too confusing...

There are no `free objects' in the Python interface to FORMS, nor is
there an easy way to add object classes written in Python.  The FORMS
interface to GL event handling is avaiable, though, so you can mix
FORMS with pure GL windows.

*Please note:* importing `fl' implies a call to the GL function
`foreground()' and to the FORMS routine `fl_init()'.

* Menu:

* Functions defined in module fl::  Functions defined in module `fl'
* Form object::                 Form object methods and data attributes
* FORMS object::                FORMS object methods and data attributes


File: python-lib.info,  Node: Functions defined in module fl,  Next: Form object,  Up: fl

Functions defined in module `fl'
--------------------------------

Module `fl' defines the following functions.  For more information
about what they do, see the description of the equivalent C function
in the FORMS documentation:

 -- function of module fl: make_form (TYPE, WIDTH, HEIGHT)
     Create a form with given type, width and height.  This returns a
     "form" object, whose methods are described below.

 -- function of module fl: do_forms ()
     The standard FORMS main loop.  Returns a Python object
     representing the FORMS object needing interaction, or the special
     value `FL.EVENT'.

 -- function of module fl: check_forms ()
     Check for FORMS events.  Returns what `do_forms' above returns,
     or `None' if there is no event that immediately needs interaction.

 -- function of module fl: set_event_call_back (FUNCTION)
     Set the event callback function.

 -- function of module fl: set_graphics_mode (RGBMODE, DOUBLEBUFFERING)
     Set the graphics modes.

 -- function of module fl: get_rgbmode ()
     Return the current rgb mode.  This is the value of the C global
     variable `fl_rgbmode'.

 -- function of module fl: show_message (STR1, STR2, STR3)
     Show a dialog box with a three-line message and an OK button.

 -- function of module fl: show_question (STR1, STR2, STR3)
     Show a dialog box with a three-line message and YES and NO
     buttons.  It returns `1' if the user pressed YES, `0' if NO.

 -- function of module fl: show_choice (STR1, STR2, STR3, BUT1, BUT2,
          BUT3)
     Show a dialog box with a three-line message and up to three
     buttons.  It returns the number of the button clicked by the user
     (`1', `2' or `3').  The BUT2 and BUT3 arguments are optional.

 -- function of module fl: show_input (PROMPT, DEFAULT)
     Show a dialog box with a one-line prompt message and text field in
     which the user can enter a string.  The second argument is the
     default input string.  It returns the string value as edited by
     the user.

 -- function of module fl: show_file_selector (MESSAGE, DIRECTORY,
          PATTERN, DEFAULT)
     Show a dialog box inm which the user can select a file.  It
     returns the absolute filename selected by the user, or `None' if
     the user presses Cancel.

 -- function of module fl: get_directory ()

 -- function of module fl: get_pattern ()

 -- function of module fl: get_filename ()
     These functions return the directory, pattern and filename (the
     tail part only) selected by the user in the last
     `show_file_selector' call.

 -- function of module fl: qdevice (DEV)

 -- function of module fl: unqdevice (DEV)

 -- function of module fl: isqueued (DEV)

 -- function of module fl: qtest ()

 -- function of module fl: qread ()

 -- function of module fl: qreset ()

 -- function of module fl: qenter (DEV, VAL)

 -- function of module fl: get_mouse ()

 -- function of module fl: tie (BUTTON, VALUATOR1, VALUATOR2)
     These functions are the FORMS interfaces to the corresponding GL
     functions.  Use these if you want to handle some GL events
     yourself when using `fl.do_events'.  When a GL event is detected
     that FORMS cannot handle, `fl.do_forms()' returns the special
     value `FL.EVENT' and you should call `fl.qread()' to read the
     event from the queue.  Don't use the equivalent GL functions!

 -- function of module fl: color ()

 -- function of module fl: mapcolor ()

 -- function of module fl: getmcolor ()
     See the description in the FORMS documentation of `fl_color',
     `fl_mapcolor' and `fl_getmcolor'.


File: python-lib.info,  Node: Form object,  Next: FORMS object,  Prev: Functions defined in module fl,  Up: fl

Form object methods and data attributes
---------------------------------------

Form objects (returned by `fl.make_form()' above) have the following
methods.  Each method corresponds to a C function whose name is
prefixed with `fl_'; and whose first argument is a form pointer;
please refer to the official FORMS documentation for descriptions.

All the `add_...' functions return a Python object representing the
FORMS object.  Methods of FORMS objects are described below.  Most
kinds of FORMS object also have some methods specific to that kind;
these methods are listed here.

 -- Method on form object: show_form (PLACEMENT, BORDERTYPE, NAME)
     Show the form.

 -- Method on form object: hide_form ()
     Hide the form.

 -- Method on form object: redraw_form ()
     Redraw the form.

 -- Method on form object: set_form_position (X, Y)
     Set the form's position.

 -- Method on form object: freeze_form ()
     Freeze the form.

 -- Method on form object: unfreeze_form ()
     Unfreeze the form.

 -- Method on form object: activate_form ()
     Activate the form.

 -- Method on form object: deactivate_form ()
     Deactivate the form.

 -- Method on form object: bgn_group ()
     Begin a new group of objects; return a group object.

 -- Method on form object: end_group ()
     End the current group of objects.

 -- Method on form object: find_first ()
     Find the first object in the form.

 -- Method on form object: find_last ()
     Find the last object in the form.

 -- Method on form object: add_box (TYPE, X, Y, W, H, NAME)
     Add a box object to the form.  No extra methods.

 -- Method on form object: add_text (TYPE, X, Y, W, H, NAME)
     Add a text object to the form.  No extra methods.

 -- Method on form object: add_clock (TYPE, X, Y, W, H, NAME)
     Add a clock object to the form.
      Method: `get_clock'.

 -- Method on form object: add_button (TYPE, X, Y, W, H, NAME)
     Add a button object to the form.
      Methods: `get_button', `set_button'.

 -- Method on form object: add_lightbutton (TYPE, X, Y, W, H, NAME)
     Add a lightbutton object to the form.
      Methods: `get_button', `set_button'.

 -- Method on form object: add_roundbutton (TYPE, X, Y, W, H, NAME)
     Add a roundbutton object to the form.
      Methods: `get_button', `set_button'.

 -- Method on form object: add_slider (TYPE, X, Y, W, H, NAME)
     Add a slider object to the form.
      Methods: `set_slider_value', `get_slider_value',
     `set_slider_bounds', `get_slider_bounds', `set_slider_return',
     `set_slider_size', `set_slider_precision', `set_slider_step'.

 -- Method on form object: add_valslider (TYPE, X, Y, W, H, NAME)
     Add a valslider object to the form.
      Methods: `set_slider_value', `get_slider_value',
     `set_slider_bounds', `get_slider_bounds', `set_slider_return',
     `set_slider_size', `set_slider_precision', `set_slider_step'.

 -- Method on form object: add_dial (TYPE, X, Y, W, H, NAME)
     Add a dial object to the form.
      Methods: `set_dial_value', `get_dial_value', `set_dial_bounds',
     `get_dial_bounds'.

 -- Method on form object: add_positioner (TYPE, X, Y, W, H, NAME)
     Add a positioner object to the form.
      Methods: `set_positioner_xvalue', `set_positioner_yvalue',
     `set_positioner_xbounds', `set_positioner_ybounds',
     `get_positioner_xvalue', `get_positioner_yvalue',
     `get_positioner_xbounds', `get_positioner_ybounds'.

 -- Method on form object: add_counter (TYPE, X, Y, W, H, NAME)
     Add a counter object to the form.
      Methods: `set_counter_value', `get_counter_value',
     `set_counter_bounds', `set_counter_step', `set_counter_precision',
     `set_counter_return'.

 -- Method on form object: add_input (TYPE, X, Y, W, H, NAME)
     Add a input object to the form.
      Methods: `set_input', `get_input', `set_input_color',
     `set_input_return'.

 -- Method on form object: add_menu (TYPE, X, Y, W, H, NAME)
     Add a menu object to the form.
      Methods: `set_menu', `get_menu', `addto_menu'.

 -- Method on form object: add_choice (TYPE, X, Y, W, H, NAME)
     Add a choice object to the form.
      Methods: `set_choice', `get_choice', `clear_choice',
     `addto_choice', `replace_choice', `delete_choice',
     `get_choice_text', `set_choice_fontsize', `set_choice_fontstyle'.

 -- Method on form object: add_browser (TYPE, X, Y, W, H, NAME)
     Add a browser object to the form.
      Methods: `set_browser_topline', `clear_browser',
     `add_browser_line', `addto_browser', `insert_browser_line',
     `delete_browser_line', `replace_browser_line', `get_browser_line',
     `load_browser', `get_browser_maxline', `select_browser_line',
     `deselect_browser_line', `deselect_browser',
     `isselected_browser_line', `get_browser', `set_browser_fontsize',
     `set_browser_fontstyle', `set_browser_specialkey'.

 -- Method on form object: add_timer (TYPE, X, Y, W, H, NAME)
     Add a timer object to the form.
      Methods: `set_timer', `get_timer'.

Form objects have the following data attributes; see the FORMS
documentation:

*Name*
     *Type*  --  *Meaning*

`window'
     int (read-only)  --  GL window id

`w'
     float  --  form width

`h'
     float  --  form height

`x'
     float  --  form x origin

`y'
     float  --  form y origin

`deactivated'
     int  --  nonzero if form is deactivated

`visible'
     int  --  nonzero if form is visible

`frozen'
     int  --  nonzero if form is frozen

`doublebuf'
     int  --  nonzero if double buffering on


File: python-lib.info,  Node: FORMS object,  Prev: Form object,  Up: fl

FORMS object methods and data attributes
----------------------------------------

Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:

 -- Method on FORMS object: set_call_back (FUNCTION, ARGUMENT)
     Set the object's callback function and argument.  When the object
     needs interaction, the callback function will be called with two
     arguments: the object, and the callback argument.  (FORMS objects
     without a callback function are returned by `fl.do_forms()' or
     `fl.check_forms()' when they need interaction.)  Call this method
     without arguments to remove the callback function.

 -- Method on FORMS object: delete_object ()
     Delete the object.

 -- Method on FORMS object: show_object ()
     Show the object.

 -- Method on FORMS object: hide_object ()
     Hide the object.

 -- Method on FORMS object: redraw_object ()
     Redraw the object.

 -- Method on FORMS object: freeze_object ()
     Freeze the object.

 -- Method on FORMS object: unfreeze_object ()
     Unfreeze the object.

FORMS objects have these data attributes; see the FORMS documentation:

*Name*
     *Type*  --  *Meaning*

`objclass'
     int (read-only)  --  object class

`type'
     int (read-only)  --  object type

`boxtype'
     int  --  box type

`x'
     float  --  x origin

`y'
     float  --  y origin

`w'
     float  --  width

`h'
     float  --  height

`col1'
     int  --  primary color

`col2'
     int  --  secondary color

`align'
     int  --  alignment

`lcol'
     int  --  label color

`lsize'
     float  --  label font size

`label'
     string  --  label string

`lstyle'
     int  --  label style

`pushed'
     int (read-only)  --  (see FORMS docs)

`focus'
     int (read-only)  --  (see FORMS docs)

`belowmouse'
     int (read-only)  --  (see FORMS docs)

`frozen'
     int (read-only)  --  (see FORMS docs)

`active'
     int (read-only)  --  (see FORMS docs)

`input'
     int (read-only)  --  (see FORMS docs)

`visible'
     int (read-only)  --  (see FORMS docs)

`radio'
     int (read-only)  --  (see FORMS docs)

`automatic'
     int (read-only)  --  (see FORMS docs)


File: python-lib.info,  Node: FL (uppercase),  Next: flp,  Prev: fl,  Up: SGI MACHINES ONLY

Standard Module `FL'
====================

This module defines symbolic constants needed to use the built-in
module `fl' (see above); they are equivalent to those defined in the C
header file `<forms.h>' except that the name prefix `FL_' is omitted.
Read the module source for a complete list of the defined names.
Suggested use:

     import fl
     from FL import *


File: python-lib.info,  Node: flp,  Next: panel,  Prev: FL (uppercase),  Up: SGI MACHINES ONLY

Standard Module `flp'
=====================

This module defines functions that can read form definitions created
by the `form designer' (`fdesign') program that comes with the FORMS
library (see module `fl' above).

For now, see the file `flp.doc' in the Python library source directory
for a description.

XXX A complete description should be inserted here!


File: python-lib.info,  Node: panel,  Next: panelparser,  Prev: flp,  Up: SGI MACHINES ONLY

Standard Module `panel'
=======================

*Please note:* The FORMS library, to which the `fl' module described
above interfaces, is a simpler and more accessible user interface
library for use with GL than the Panel Module (besides also being by a
Dutch author).

This module should be used instead of the built-in module `pnl' to
interface with the *Panel Library*.

The module is too large to document here in its entirety.  One
interesting function:

 -- function of module panel: defpanellist (FILENAME)
     Parses a panel description file containing S-expressions written
     by the *Panel Editor* that accompanies the Panel Library and
     creates the described panels.  It returns a list of panel objects.

*Warning:* the Python interpreter will dump core if you don't create a
GL window before calling `panel.mkpanel()' or `panel.defpanellist()'.


File: python-lib.info,  Node: panelparser,  Next: pnl,  Prev: panel,  Up: SGI MACHINES ONLY

Standard Module `panelparser'
=============================

This module defines a self-contained parser for S-expressions as output
by the Panel Editor (which is written in Scheme so it can't help
writing S-expressions).  The relevant function is
`panelparser.parse_file(FILE)' which has a file object (not a
filename!) as argument and returns a list of parsed S-expressions.
Each S-expression is converted into a Python list, with atoms converted
to Python strings and sub-expressions (recursively) to Python lists.
For more details, read the module file.


File: python-lib.info,  Node: pnl,  Next: jpeg,  Prev: panelparser,  Up: SGI MACHINES ONLY

Built-in Module `pnl'
=====================

This module provides access to the *Panel Library* built by NASA Ames
(to get it, send e-mail to [e-mail]).  All access to
it should be done through the standard module `panel', which
transparantly exports most functions from `pnl' but redefines
`pnl.dopanel()'.

*Warning:* the Python interpreter will dump core if you don't create a
GL window before calling `pnl.mkpanel()'.

The module is too large to document here in its entirety.


File: python-lib.info,  Node: jpeg,  Next: imgfile,  Prev: pnl,  Up: SGI MACHINES ONLY

Built-in Module `jpeg'
======================

The module jpeg provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group. JPEG is a (draft?)
standard for compressing pictures.  For details on jpeg or the
Indepent JPEG Group software refer to the JPEG standard or the
documentation provided with the software.

The jpeg module defines these functions:

 -- function of module jpeg: compress (DATA, W, H, B)
     Treat data as a pixmap of width w and height h, with b bytes per
     pixel.  The data is in sgi gl order, so the first pixel is in the
     lower-left corner. This means that lrectread return data can
     immedeately be passed to compress.  Currently only 1 byte and 4
     byte pixels are allowed, the former being treaded as greyscale
     and the latter as RGB color.  Compress returns a string that
     contains the compressed picture, in JFIF format.

 -- function of module jpeg: decompress (DATA)
     Data is a string containing a picture in JFIF format. It returns a
     tuple `(DATA, WIDTH, HEIGHT, BYTESPERPIXEL)'.  Again, the data is
     suitable to pass to lrectwrite.

 -- function of module jpeg: setoption (NAME, VALUE)
     Set various options.  Subsequent compress and decompress calls
     will use these options.  The following options are available:
    `'forcegray''
          Force output to be grayscale, even if input is RGB.

    `'quality''
          Set the quality of the compressed image to a value between
          `0' and `100' (default is `75').  Compress only.

    `'optimize''
          Perform huffman table optimization.  Takes longer, but
          results in smaller compressed image.  Compress only.

    `'smooth''
          Perform inter-block smoothing on uncompressed image.  Only
          useful for low-quality images.  Decompress only.

Compress and uncompress raise the error jpeg.error in case of errors.


File: python-lib.info,  Node: imgfile,  Next: imageop,  Prev: jpeg,  Up: SGI MACHINES ONLY

Built-in module `imgfile'
=========================

The imgfile module allows python programs to access SGI imglib image
files (also known as `.rgb' files).  The module is far from complete,
but is provided anyway since the functionality that there is is enough
in some cases.  Currently, colormap files are not supported.

The module defines the following variables and functions:

 -- exception of module imgfile: error
     This exception is raised on all errors, such as unsupported file
     type, etc.

 -- function of module imgfile: getsizes (FILE)
     This function returns a tuple `(X, Y, Z)' where X and Y are the
     size of the image in pixels and Z is the number of bytes per
     pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels are
     currently supported.

 -- function of module imgfile: read (FILE)
     This function reads and decodes the image on the specified file,
     and returns it as a python string. The string has either 1 byte
     greyscale pixels or 4 byte RGBA pixels. The bottom left pixel is
     the first in the string. This format is suitable to pass to
     `gl.lrectwrite', for instance.

 -- function of module imgfile: readscaled (FILE, X, Y, FILTER, BLUR)
     This function is identical to read but it returns an image that is
     scaled to the given X and Y sizes. If the FILTER and BLUR
     parameters are omitted scaling is done by simply dropping or
     duplicating pixels, so the result will be less than perfect,
     especially for computer-generated images.

     Alternatively, you can specify a filter to use to smoothen the
     image after scaling. The filter forms supported are `'impulse'',
     `'box'', `'triangle'', `'quadratic'' and `'gaussian''. If a
     filter is specified BLUR is an optional parameter specifying the
     blurriness of the filter. It defaults to `1.0'.

     Readscaled makes no attempt to keep the aspect ratio correct, so
     that is the users' responsibility.

 -- function of module imgfile: write (FILE, DATA, X, Y, Z)
     This function writes the RGB or greyscale data in DATA to image
     file FILE. X and Y give the size of the image, Z is 1 for 1 byte
     greyscale images or 3 for RGB images (which are stored as 4 byte
     values of which only the lower three bytes are used).  These are
     the formats returned by `gl.lrectread'.


File: python-lib.info,  Node: imageop,  Prev: imgfile,  Up: SGI MACHINES ONLY

Built-in module `imageop'
=========================

The imageop module contains some useful operations on images.  It
operates on images consisting of 8 or 32 bit pixels stored in python
strings. This is the same format as used by `gl.lrectwrite' and the
`imgfile' module.

The module defines the following variables and functions:

 -- exception of module imageop: error
     This exception is raised on all errors, such as unknown number of
     bits per pixel, etc.

 -- function of module imageop: crop (IMAGE, PSIZE, WIDTH, HEIGHT, X0,
          Y0, X1, Y1)
     This function takes the image in `image', which should by `width'
     by `height' in size and consist of pixels of `psize' bytes, and
     returns the selected part of that image. `X0', `y0', `x1' and
     `y1' are like the `lrectread' parameters, i.e. the boundary is
     included in the new image.  The new boundaries need not be inside
     the picture. Pixels that fall outside the old image will have
     their value set to zero.  If `x0' is bigger than `x1' the new
     image is mirrored. The same holds for the y coordinates.

 -- function of module imageop: scale (IMAGE, PSIZE, WIDTH, HEIGHT,
          NEWWIDTH, NEWHEIGHT)
     This function returns a `image' scaled to size `newwidth' by
     `newheight'. No interpolation is done, scaling is done by
     simple-minded pixel duplication or removal. Therefore,
     computer-generated images or dithered images will not look nice
     after scaling.

 -- function of module imageop: tovideo (IMAGE, PSIZE, WIDTH, HEIGHT)
     This function runs a vertical low-pass filter over an image. It
     does so by computing each destination pixel as the average of two
     vertically-aligned source pixels. The main use of this routine is
     to forestall excessive flicker if the image is displayed on a
     video device that uses interlacing, hence the name.

 -- function of module imageop: grey2mono (IMAGE, WIDTH, HEIGHT,
          THRESHOLD)
     This function converts a 8-bit deep greyscale image to a 1-bit
     deep image by tresholding all the pixels. The resulting image is
     tightly packed and is probably only useful as an argument to
     `mono2grey'.

 -- function of module imageop: dither2mono (IMAGE, WIDTH, HEIGHT)
     This function also converts an 8-bit greyscale image to a 1-bit
     monochrome image but it uses a (simple-minded) dithering
     algorithm.

 -- function of module imageop: mono2grey (IMAGE, WIDTH, HEIGHT, P0,
          P1)
     This function converts a 1-bit monochrome image to an 8 bit
     greyscale or color image. All pixels that are zero-valued on
     input get value `p0' on output and all one-value input pixels get
     value `p1' on output. To convert a monochrome black-and-white
     image to greyscale pass the values `0' and `255' respectively.

 -- function of module imageop: grey2grey4 (IMAGE, WIDTH, HEIGHT)
     Convert an 8-bit greyscale image to a 4-bit greyscale image
     without dithering.

 -- function of module imageop: grey2grey2 (IMAGE, WIDTH, HEIGHT)
     Convert an 8-bit greyscale image to a 2-bit greyscale image
     without dithering.

 -- function of module imageop: dither2grey2 (IMAGE, WIDTH, HEIGHT)
     Convert an 8-bit greyscale image to a 2-bit greyscale image with
     dithering. As for `dither2mono', the dithering algorithm is
     currently very simple.

 -- function of module imageop: grey42grey (IMAGE, WIDTH, HEIGHT)
     Convert a 4-bit greyscale image to an 8-bit greyscale image.

 -- function of module imageop: grey22grey (IMAGE, WIDTH, HEIGHT)
     Convert a 2-bit greyscale image to an 8-bit greyscale image.


File: python-lib.info,  Node: SUN SPARC MACHINES ONLY,  Next: AUDIO TOOLS,  Prev: SGI MACHINES ONLY,  Up: Top

SUN SPARC MACHINES ONLY
***********************

* Menu:

* sunaudiodev::                 Built-in module `sunaudiodev'


File: python-lib.info,  Node: sunaudiodev,  Up: SUN SPARC MACHINES ONLY

Built-in module `sunaudiodev'
=============================

This module allows you to access the sun audio interface. The sun
audio hardware is capable of recording and playing back audio data in
U-LAW format with a sample rate of 8K per second. A full description
can be gotten with `man audio'.

The module defines the following variables and functions:

 -- exception of module sunaudiodev: error
     This exception is raised on all errors. The argument is a string
     describing what went wrong.

 -- function of module sunaudiodev: open (MODE)
     This function opens the audio device and returns a sun audio
     device object. This object can then be used to do I/O on. The
     MODE parameter is one of `'r'' for record-only access, `'w'' for
     play-only access, `'rw'' for both and `'control'' for access to
     the control device. Since only one process is allowed to have the
     recorder or player open at the same time it is a good idea to
     open the device only for the activity needed. See the audio
     manpage for details.

* Menu:

* Audio device object methods::  Audio device object methods


File: python-lib.info,  Node: Audio device object methods,  Up: sunaudiodev

Audio device object methods
---------------------------

The audio device objects are returned by `open' define the following
methods (except `control' objects which only provide getinfo, setinfo
and drain):

 -- Method on audio device: close ()
     This method explicitly closes the device. It is useful in
     situations where deleting the object does not immediately close
     it since there are other references to it. A closed device should
     not be used again.

 -- Method on audio device: drain ()
     This method waits until all pending output is processed and then
     returns.  Calling this method is often not necessary: destroying
     the object will automatically close the audio device and this
     will do an implicit drain.

 -- Method on audio device: flush ()
     This method discards all pending output. It can be used avoid the
     slow response to a user's stop request (due to buffering of up to
     one second of sound).

 -- Method on audio device: getinfo ()
     This method retrieves status information like input and output
     volume, etc. and returns it in the form of an audio status
     object. This object has no methods but it contains a number of
     attributes describing the current device status. The names and
     meanings of the attributes are described in
     `/usr/include/sun/audioio.h' and in the audio man page. Member
     names are slightly different from their C counterparts: a status
     object is only a single structure. Members of the `play'
     substructure have `o_' prepended to their name and members of the
     `record' structure have `i_'. So, the C member `play.sample_rate'
     is accessed as `o_sample_rate', `record.gain' as `i_gain' and
     `monitor_gain' plainly as `monitor_gain'.

 -- Method on audio device: ibufcount ()
     This method returns the number of samples that are buffered on the
     recording side, i.e.  the program will not block on a `read' call
     of so many samples.

 -- Method on audio device: obufcount ()
     This method returns the number of samples buffered on the playback
     side. Unfortunately, this number cannot be used to determine a
     number of samples that can be written without blocking since the
     kernel output queue length seems to be variable.

 -- Method on audio device: read (SIZE)
     This method reads SIZE samples from the audio input and returns
     them as a python string. The function blocks until enough data is
     available.

 -- Method on audio device: setinfo (STATUS)
     This method sets the audio device status parameters. The STATUS
     parameter is an device status object as returned by `getinfo' and
     possibly modified by the program.

 -- Method on audio device: write (SAMPLES)
     Write is passed a python string containing audio samples to be
     played.  If there is enough buffer space free it will immedeately
     return, otherwise it will block.

There is a companion module, `SUNAUDIODEV', which defines useful
symbolic constants like `MIN_GAIN', `MAX_GAIN', `SPEAKER', etc. The
names of the constants are the same names as used in the C include file
`<sun/audioio.h>', with the leading string `AUDIO_' stripped.

Useability of the control device is limited at the moment, since there
is no way to use the 'wait for something to happen' feature the device
provides. This is because that feature makes heavy use of signals, and
these do not map too well onto Python.


File: python-lib.info,  Node: AUDIO TOOLS,  Next: CRYPTOGRAPHIC EXTENSIONS,  Prev: SUN SPARC MACHINES ONLY,  Up: Top

AUDIO TOOLS
***********

* Menu:

* audioop::                     Built-in module `audioop'